State Reset API

The following document outlines the details of the State Reset API.

API Description

Objective

The State Reset API is designed to reset the state of a CPR transaction. It supports two main actions: clear_continuous_state and clear_complete_state, enabling administrators to reset user application states when issues occur or when users need to retry specific steps.

Input	Output
Authentication headers and state reset parameters	Confirmation of successful state reset operation or detailed error information

API URL

https://review-api.idv.hyperverge.co/api/v1/cpr/application/state-reset

API Endpoint

state-reset

Overview

The State Reset API is RESTful and uses standard HTTP verbs and status codes. The responses are in JSON format and you should send all data in JSON format through a POST request.

Authentication

You need a unique pair of application ID ( appId ) and application key (appKey) from HyperVerge to verify your identity for accessing the State Reset API.

Important

Due to the sensitive nature of this API, IP whitelisting is mandatory. This API should be integrated in the backend only and not directly in the frontend, as IP whitelisting requires a limited set of known server IPs. Please reach out to HyperVerge support to get your IP whitelisted.

Reset Types (`action`)

The State Reset API supports two distinct reset operations, each designed for specific scenarios and use cases:

1. Clear Continuous State (`clear_continuous_state`)

Purpose: Reset the application state from a specific module onwards while preserving all progress made in earlier modules.

Use Case: This reset type is ideal when a particular step in the user journey fails or encounters issues that require retry, but the user has successfully completed previous modules that should not be lost.

Behavior: The system clears the state for the specified module and all subsequent modules in the workflow execution order, while maintaining all data and progress from modules that were completed before the reset point.

Required Parameter: moduleId - The unique identifier of the module from which the reset should begin. This parameter is mandatory and must correspond to a valid module in the workflow.

Example Scenario: If a user successfully completes "Identity Verifcation" and "Digilocker" but encounters an issue during "Selfie Validation", you can reset from the selfie module while preserving the personal and address information.

2. Clear Complete State (`clear_complete_state`)

Purpose: Reset the entire application state, removing all stored progress and requiring the user to restart the complete workflow from the beginning.

Use Case: This reset type is used when the entire workflow needs to be restarted due to fundamental issues, configuration changes, or when a fresh start is required for the user journey.

Behavior: The system removes all stored state data associated with the transaction, including progress from all modules, form submissions, document uploads, and verification results. The user will need to re-enter all information and re-upload all documents.

Required Parameter: None - This reset type affects the entire workflow and does not require any module-specific parameters.

Example Scenario: If there are significant changes to the workflow configuration or if the user needs to start completely fresh due to major issues, this reset type ensures a clean slate for the entire application process.

API Request Details

Method - `POST`

Headers

Parameter	Mandatory or Optional	Description	Valid Values
appid	Mandatory	The application ID shared by HyperVerge	Not Applicable - this is a unique value
transactionid	Mandatory	The unique transaction ID for the user journey	Not Applicable - this is a unique value

Input

The following table provides the details of the parameters required for the State Reset API's request body:

Parameter	Mandatory or Optional	Description	Allowed Values	Default Value
`action`	Mandatory	The type of state reset operation to be performed	`clear_continuous_state`, `clear_complete_state`	Not Applicable
`moduleId`	Conditionally Optional (Required if action is `clear_continuous_state`; Optional if action is `clear_complete_state`)	The identifier of the specific module from which state should be reset	Valid module identifier, for example, `"kyc_verification"`	Not Applicable
`reviewerId`	Mandatory	The e-mail address or ID of the reviewer who triggered the state reset	Valid e-mail address or identifier	Not Applicable

Request

The following code snippets demonstrate standard curl requests for the State Reset API:

Clear Continuous State Request
Clear Complete State Request

curl --location --request POST 'https://review-api.idv.hyperverge.co/api/v1/cpr/application/state-reset' \
--header 'appid: <Enter_the_HyperVerge_appId>' \
--header 'transactionid: <Enter_the_HyperVerge_transaction_ID>' \
--header 'Content-Type: application/json' \
--data '{
    "action": "clear_continuous_state",
    "moduleId": "<Enter_the_module_ID>",
    "reviewerId": "<Enter_the_reviewer_ID>"
}'

curl --location --request POST 'https://review-api.idv.hyperverge.co/api/v1/cpr/application/state-reset' \
--header 'appid: <Enter_the_HyperVerge_appId>' \
--header 'transactionid: <Enter_the_HyperVerge_transaction_ID>' \
--header 'Content-Type: application/json' \
--data '{
    "action": "clear_complete_state",
    "reviewerId": "<Enter_the_reviewer_ID>"
}'

Success Response

The following code snippet demonstrates a success response from the State Reset API:

{
  "status": "success",
  "statusCode": 200,
  "result": {
    "message": "<Success_Message>"
  }
}

Success Response Details

The following table outlines the details of the success response from the State Reset API:

Parameter	Type	Description
status	string	The status of the request
statusCode	number	The HTTP status code of the response
result.message	string	The confirmation message indicating successful state reset operation

Error Responses

The following are some error responses from the State Reset API:

Dashboard State Reset Not Enabled
Missing Required Header
Missing Required Field
Invalid Action Value

{
  "status": "failure",
  "statusCode": 400,
  "error": "Dashboard state reset is not enabled"
}

{
  "status": "failure",
  "statusCode": 422,
  "error": "\"appid\" is required"
}

{
  "status": "failure",
  "statusCode": 422,
  "error": "\"action\" is required"
}

{
  "status": "failure",
  "statusCode": 422,
  "error": "\"action\" must be one of [clear_continuous_state, clear_complete_state]"
}

Missing ModuleId
ModuleId Not Allowed
Unauthorized Access
Transaction Not Found

{
  "status": "failure",
  "statusCode": 422,
  "error": "\"moduleId\" is required"
}

{
  "status": "failure",
  "statusCode": 422,
  "error": "\"moduleId\" is not allowed"
}

{
  "status": "failure",
  "statusCode": 401,
  "error": "Unauthorized"
}

{
  "status": "failure",
  "statusCode": 404,
  "error": "Transaction not found"
}

Workflow Not Found
State Not Found
Internal Server Error

{
  "status": "failure",
  "statusCode": 404,
  "error": "Workflow not found"
}

{
  "status": "failure",
  "statusCode": 404,
  "error": "state_not_found"
}

{
  "status": "failure",
  "statusCode": 500,
  "error": "<Error_Message>"
}

Error Response Details

A failure or error response from the module contains a failure status, with a relevant status code and error message.
The following table lists all error responses:

Status Code	Error Message	Error Description
400	Dashboard state reset is not enabled	The dashboard state reset functionality is not enabled for this workflow
401	Unauthorized	The request contains invalid or missing authentication credentials
404	Transaction not found	The specified transaction was not found in the system
404	Workflow not found	The specified workflow was not found in the system
404	state_not_found	The transaction state was not found on CPR or has expired
422	"action" is required	The request is missing the required action field in the request body
422	"action" must be one of [clear_continuous_state, clear_complete_state]	The request contains an invalid action value
422	"appid" is required	The request is missing the required appid header parameter
422	"moduleId" is required	The request is missing the required moduleId field for clear_continuous_state action
422	"moduleId" is not allowed	The request contains moduleId field which is not allowed for clear_complete_state action
422	"transactionid" is required	The request is missing the required transactionid header parameter
500	Internal Server Error	Please contact HyperVerge for investigation

API Description​

Objective​

API URL​

API Endpoint​

Overview​

Authentication​

Reset Types (action)​

1. Clear Continuous State (clear_continuous_state)​

2. Clear Complete State (clear_complete_state)​

API Request Details

Method - POST